---
title: TypeScript
description: Aprenda como utilizar o suporte integrado a TypeScript do Astro.
i18nReady: true
---
import Since from '~/components/Since.astro'
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

Astro vem com suporte integrado para [TypeScript](https://www.typescriptlang.org/). Você pode importar arquivos `.ts` e `.tsx` em seu projeto Astro, escrever código TypeScript dentro de seu [componente Astro](/pt-br/basics/astro-components/#o-script-do-componente), e até mesmo utilizar um arquivo [`astro.config.ts`](/pt-br/guides/configuring-astro/#o-arquivo-de-configuração-astro) se você quiser.

Usando TypeScript, você pode evitar erros em tempo de execução ao definir os formatos dos objetos e componentes no seu código. Por exemplo, se você usa TypeScript para definir o [tipo das props do seu componente](#propriedades-de-componentes), você vai receber um erro no seu editor se você definir uma prop que seu componente não aceita.

Você não precisa escrever código TypeScript nos seus projetos com Astro para se beneficiar dele. O Astro sempre trata seu código do componente como TypeScript, e a [extensão para VSCode do Astro](/pt-br/editor-setup/) vai inferir o tanto quanto pode para fornecer preenchimento automático, dicas e erros no seu editor.

O servidor de desenvolvimento do Astro não executará nenhuma checagem de tipos, mas você pode usar um [script separado](#checagem-de-tipos) para checar erros de tipo pela linha de comando.

## Configuração
Projetos iniciais do Astro incluem um arquivo `tsconfig.json` no seu projeto. Mesmo que você não escreva código TypeScript, esse arquivo é importante para que ferramentas como o Astro e o VS Code saibam como entender o seu projeto. Algumas funcionalidades (como importação de pacotes do npm) não são completamente suportadas em nosso editor sem um arquivo `tsconfig.json`. Se você instalar Astro manualmente, certifique-se de criar esse arquivo.

Três templates extensíveis de `tsconfig.json` são inclusos no Astro: `base`, `strict` e `strictest`. O template `base` habilita suporte para funcionalidades modernas do JavaScript e também é usado como uma base para os outros templates. Nós recomendamos usar `strict` (estrito) ou `strictest` (mais estrito) se você planeja escrever TypeScript em seu projeto. Você pode ver e comparar a configuração dos três templates em [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/).

Para herdar de um dos templates, utilize [a opção `extends`](https://www.typescriptlang.org/tsconfig#extends):

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/base"
}
```

Adicionalmente, nossos templates incluem um arquivo `env.d.ts` dentro do diretório `src` para providenciar [tipos de cliente do Vite](https://vitejs.dev/guide/features.html#client-types) para seu projeto:

```typescript title="env.d.ts"
/// <reference types="astro/client" />
```

Se você não está usando VSCode, você pode instalar o [plugin Astro TypeScript](https://www.npmjs.com/package/@astrojs/ts-plugin) para suportar a importação de arquivos `.astro` de arquivos `.ts` (que pode ser útil para reexportação).

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @astrojs/ts-plugin
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @astrojs/ts-plugin
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @astrojs/ts-plugin
  ```
  </Fragment>
</PackageManagerTabs>

Então, adicione o seguinte no seu `tsconfig.json`:

```json title="tsconfig.json"
  "compilerOptions": {
    "plugins": [
      {
        "name": "@astrojs/ts-plugin"
      },
    ],
  }
```

Para checar que o plugin está funcionando, crie um arquivo `.ts` e importe um componente do Astro nele. Você não deve ter nenhuma mensagem de aviso do seu editor.


### Frameworks de UI

Se o seu projeto utiliza um [framework de UI](/pt-br/guides/framework-components/), configurações adicionais dependendo do framework podem ser necessárias. Por favor veja a documentação do TypeScript do seu framework para mais informações. ([Vue](https://vuejs.org/guide/typescript/overview.html#using-vue-with-typescript), [React](https://react-typescript-cheatsheet.netlify.app/docs/basic/setup), [Preact](https://preactjs.com/guide/v10/typescript), [Solid](https://www.solidjs.com/guides/typescript))

## Importações de Tipos

Utilize importações e exportações explícitas de tipos sempre que possível.

```js del={1} ins={2} ins="type"
import { AlgumTipo } from './script';
import type { AlgumTipo } from './script';
```

Dessa forma, você evita casos extremos onde o bundler do Astro pode tentar incorretamente fazer bundle do seus tipos importados como se fossem JavaScript.

Você pode configurar o TypeScript para reforçar importações de tipos no seu arquivo `.tsconfig`. Defina [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax) como `true`. O TypeScript verificará suas importações e informará quando `import type` deve ser usado. Esta configuração está habilitada por padrão em todas as nossas predefinições.

```json title="tsconfig.json" ins={3}
  {
    "compilerOptions": {
      "verbatimModuleSyntax": true
    }
  }
```

## Aliases de Importação

Astro suporta [aliases de importação](/pt-br/guides/aliases/) que você define na configuração `paths` do seu `tsconfig.json` e `jsconfig.json`. [Leia nosso guia](/pt-br/guides/aliases/) para aprender mais.


```astro title="src/pages/sobre/nate.astro" "@components" "@layouts"
---
import OlaMundo from '@components/OlaMundo.astro';
import Layout from '@layouts/Layout.astro';
---
```

```json title="tsconfig.json" {5-6}
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"]
    }
  }
}
```

## Estendendo `window` e `globalThis`

Você pode querer adicionar uma propriedade para o objeto global. Você pode fazer isso adicionando declarações de nível superior usando a palavra-chave `declare` ao seu arquivo `env.d.ts`:

```ts title="env.d.ts"
declare const minhaString: string;
declare function minhaFuncao(): boolean;
```

Isso fornecerá tipos para `globalThis.minhaString` e `globalThis.minhaFuncao`, assim como para `window.minhaString` e `window.minhaFuncao`.

Note que `window` só está disponível no código no lado do cliente. O `globalThis` está disponível no lado do servidor e no lado do cliente, mas seu valor no lado do servidor não é compartilhado com o cliente.

Se você só quer definir o tipo de uma propriedade no objeto `window`, forneça uma interface `Window` ao invés disso:

```ts title="env.d.ts"
interface Window {
	minhaFuncao(): boolean;
}
```

## Propriedades de Componentes

O Astro suporta a tipagem das propriedades dos seus componentes via TypeScript. Para habilitar, exporte uma interface TypeScript `Props` de seu componente Astro. A [extensão para VSCode do Astro](/pt-br/editor-setup/) irá automaticamente procurar pela exportação de `Props` e te dar suporte a TypeScript quando você utilizar aquele componente dentro de outro template.
```astro title="src/components/OlaProps.astro" ins={2-5}
---
export interface Props {
  nome: string;
  saudacao?: string;
}
const { saudacao = 'Olá', nome } = Astro.props;
---
<h2>{saudacao}, {nome}!</h2>
```

### Padrões de tipo de prop comuns

- Se seu componente não recebe props ou conteúdo em slot, você pode usar `type Props = Record<string, never>`.

- Se seu componente deve receber filhos em seu slot padrão, você pode impor isso usando `type Props = { children: any; };`.

## Utilitários de Tipagem

<Since v="1.6.0" />

O Astro vem com alguns tipos utilitários integrados para padrões de tipo de props comuns. Eles estão disponíveis dentro do entrypoint `astro/types`.

### Atributos HTML integrados

O Astro fornece os tipos `HTMLAttributes` para checar que sua marcação está usando atributos HTML válidos. Você pode usar esses tipos para ajudar a construir as props de componentes.

Por exemplo, se você está construindo um componente `<Link>`, você pode fazer o seguinte para espelhar os atributos padrão de tags `<a>` nos tipos da prop do seu componente.

```astro title="src/components/Link.astro" ins="HTMLAttributes" ins="HTMLAttributes<'a'>"
---
import type { HTMLAttributes } from 'astro/types';
// use `type`
type Props = HTMLAttributes<'a'>;
// ou estenda com uma `interface`
interface Props extends HTMLAttributes<'a'> {
  minhaProp?: boolean;
}
const { href, ...attrs } = Astro.props;
---
<a href={href} {...attrs}>
  <slot />
</a>
```

Também é possível estender as definições JSX padrões para adicionar atributos que não são padrões redeclarando o namespace `astroHTML.JSX` em um arquivo `d.ts`.

```ts
// src/custom-attributes.d.ts

declare namespace astroHTML.JSX {
  interface HTMLAttributes {
    'data-count'?: number;
    'data-label'?: string;
  }

  // Adiciona uma propriedade CSS personalizada ao objeto de estilo
  interface CSSProperties {
    '--theme-color'?: 'black' | 'white';
  }
}
```

:::note
`astroHTML` é injetado globalmente dentro de componentes `.astro`. Para utilizá-lo em arquivos TypeScript, utilize uma [diretiva de barra tripla](https://www.typescriptlang.org/pt/docs/handbook/triple-slash-directives.html):

```ts
/// <reference types="astro/astro-jsx" />

type MeusAtributos = astroHTML.JSX.ImgHTMLAttributes;
```
:::

### `ComponentProps` type

<p><Since v="4.3.0" /></p>

Esta exportação de tipo permite que você referencie as `Props` aceitadas por outro componente, mesmo que o componente não exporte o tipo `Props` diretamente.

O exemplo seguinte mostra a utilidade de usar `ComponentProps` de `astro/types` para referenciar os tipos de um componente `<Button />` `Props`:

```astro title="src/pages/index.astro"
---
import type { ComponentProps } from 'astro/types';

import Button from "./Button.astro";

type ButtonProps = ComponentProps<typeof Button>;
---
```

### Tipo polimórfico

<p><Since v="2.5.0" /></p>

Astro inclui um utilitário para tornar mais fácil construir componentes que podem renderizar como elementos HTML diferentes com segurança total de tipo. Isso é útil para componentes como `<Link>` que podem renderizar como `<a>` ou `<button>` dependendo das props passadas para ele.

O exemplo abaixo implementa um componente totalmente tipado e polimórfico que pode renderizar como qualquer elemento HTML. O tipo [`HTMLTag`](#atributos-html-integrados) é usado para garantir que a prop `as` é um elemento HTML válido.

```astro
---
import type { HTMLTag, Polymorphic } from 'astro/types';

type Props<Tag extends HTMLTag> = Polymorphic<{ as: Tag }>;

const { as: Tag, ...props } = Astro.props;
---

<Tag {...props} />
```

### Inferir os tipos do `getStaticPaths()`

<p><Since v="2.1.0" /></p>

Astro inclui utilitários para trabalhar com os tipos retornados pela sua função [`getStaticPaths()`](/pt-br/reference/api-reference/#getstaticpaths) para rotas dinâmicas.

Você pode obter o tipo de [`Astro.params`](/pt-br/reference/api-reference/#astroparams) com `InferGetStaticParamsType` e o tipo de [`Astro.props`](/pt-br/reference/api-reference/#astroprops) com `InferGetStaticPropsType`:

```astro title="src/pages/posts/[...slug].astro" {2,14-15}
---
import type { InferGetStaticParamsType, InferGetStaticPropsType, GetStaticPaths } from 'astro';

export const getStaticPaths = (async () => {
  const posts = await getCollection('blog');
  return posts.map((post) => {
    return {
      params: { slug: post.slug },
      props: { draft: post.data.draft, title: post.data.title },
    };
  });
}) satisfies GetStaticPaths;

type Params = InferGetStaticParamsType<typeof getStaticPaths>;
type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { slug } = Astro.params as Params;
//               			 ^? { slug: string; }
const { title } = Astro.props;
//                			^? { draft: boolean; title: string; }
---
```

## Checagem de Tipos

Para ver erros de tipagem em seu editor, por favor certifique-se de que você tem a [extensão Astro para VS Code](/pt-br/editor-setup/) instalada. Por favor note de que os comandos `astro start` e `astro build` irão transpilar o código com esbuild, porém não executará nenhuma checagem de tipos. Para prevenir o seu código de fazer build quando conter erros de TypeScript, mude o seu script "build" no `package.json` para o seguinte:

```json title="package.json" del={2} ins={3} ins="astro check &&"
  "scripts": {
    "build": "astro build",
    "build": "astro check && astro build",
  },
```

:::note
`astro check` verifica todos os arquivos incluídos em seu projeto TypeScript. Para verificar tipos em arquivos Svelte e Vue, você pode usar os pacotes [`svelte-check`](https://www.npmjs.com/package/svelte-check) e [`vue-tsc`](https://www.npmjs.com/package/vue-tsc), respectivamente.
:::

import ReadMore from '~/components/ReadMore.astro'

<ReadMore>Leia mais sobre [a importação de arquivos `.ts`](/pt-br/guides/imports/#typescript) no Astro.</ReadMore>

<ReadMore>Leia mais sobre [Configuração TypeScript](https://www.typescriptlang.org/tsconfig/).</ReadMore>

## Solução de Problemas

### Erros ao fazer a tipagem de múltiplos frameworks JSX ao mesmo tempo

Um problema pode surgir ao se utilizar múltiplos frameworks JSX no mesmo projeto, já que cada framework requer configurações diferentes, e as vezes até conflitantes, dentro de `tsconfig.json`.

**Solução**: Defina a [opção `jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource) para `react` (padrão), `preact` ou `solid-js` dependendo do seu framework mais utilizado. Então, utilize um [comentário pragma](https://www.typescriptlang.org/docs/handbook/jsx.html#configuring-jsx) dentro de qualquer arquivo conflitante de outro framework.

Para a opção padrão de `jsxImportSource: react`, você usaria:

```jsx
// Para Preact
/** @jsxImportSource preact */

// Para Solid
/** @jsxImportSource solid-js */
```
